Build Instructions
What follows are build instructions and notes for the various
OS's that AmphetaDesk has been successfully developed on. The
below mostly focuses on creating the runtimes for Windows and
Mac's, but does cover some environment aspects. If you
have no intention of developing or adding code to AmphetaDesk, you
can leave this page. This page is NOT for end-users - only
developers or hackers. If you're looking for install
instructions, check the README.txt.
Required Perl Modules
There are a number of Perl modules that AmphetaDesk needs
to run successfully. Most of these modules are installed on normal
systems since they're pretty common for Perl use, but some, like
XML::Parser and XML::Simple, require the expat
C library, which may or may not be installed. If you're
planning on building AmphetaDesk, it's probably a good idea to
make sure you have the latest modules installed. Under
ActiveState's ppm, you'd want to issue a
verify command. Under a normal CPAN shell, you'd
do r instead.
On Linux systems, you can run perl -MCPAN -eshell
and then install Module::Name to install specific
modules. On Windows, you'd use the ActiveState ppm
command lineutility, with the same install line. Mac's require
that you use the special cpan-mac
conversion to download and install the modules.
The most important modules are contained within
Bundle::LWP, libwww-perl and
XML::Parser. Make sure these packages are
installed on your system, and you should be all set. Specific
third party modules, like XML::Simple and
Text::Template are shipped with AmphetaDesk
in the lib/ diretory.
Win32 Build Notes
The Win32 build of AmphetaDesk is compiled with
ActiveState Perl 5.6.0.623
and Perl2EXE v4.03. We've
had some difficulty with crashes when compiling with later
versions of either of those tools - we're still looking into the
cause. When compiling for Win32, make sure that the AmphetaDesk.pl
file and all files in the lib/ and template/
directories are set for DOS line feeds. This should be done automatically
on a fresh CVS checkout.
To build the Win32 GUI, you'll need some Perl modules intended
only for Windows. You can install Win32::API via
the ppm command line utility, along with
Win32::TieRegistry. For AmphetaDesk v0.93, we've
used versions 0.01 and 0.23 respectively. For the Win32::GUI
module, however, you'll have to get the latest download from
SourceForge
(v0.0.665) and follow the install instructions within.
To create the Win32 binary:
- Open
AmphetaDesk.pl and uncomment the three lines that end with "for windows compile".
- Rename the
lib/ directory to lib2/ (so that the modules won't be compiled into the .exe).
- Open a DOS window and
cd to the AmphetaDesk source directory.
- Run
perl2exe -gui -icon=templates/default/gui/win_icon.ico
-perloptions=-p2x_noshow_includes AmphetaDesk.pl (all one line).
- Rename
lib2/ back to lib/.
This will create an AmphetaDesk.exe file within
your AmphetaDesk source directory. At this point, manually test
the compiled .exe file for stability. When you're
satisifed that things are working fine, we'll finalize our build
by preping the directory for archiving into our final zip file.
You should remove the following files and directories, which will
insure a default installation of AmphetaDesk:
- All
CVS/ directories.
- Anything in the
data/channels/ directory.
- All screenshots under
docs/images/.
- The
data/myChannels.opml file (and any backups).
- The
data/mySettings.xml file (and any backups).
At this point, you should be ready to create the archive,
named according to the format below.
Macintosh (OS 7.5.x through 9.x) Build Notes
NOTE: See this fatal bug concerning AmphetaDesk v0.93 and MacPerl 5.6.1.
NOTE: The instructions below are valid only for v0.92 - AmphetaDesk v0.93 doesn't yet exist.
The Macintosh build of AmphetaDesk uses a
not-publically-released version of MacPerl 5.2.1a1 and some
modifications to the OS specific libraries within. You can find
these libraries and instructions on how to update at
Alan Fry's site.
These are required for using the Mac GUI for AmphetaDesk (which
currently hasn't shipped due to some nasty bugs still hanging
around). When compiling the Macintosh build, make sure that the
AmphetaDesk.pl file and all files in the
lib/ directory are set for Macintosh line feeds.
We also need RuntimeBuilder
to create the distributable runtime. This utility has some bugs,
but has proven useful enough for now. To prevent a fatal error on
some machines, open up RuntimeBuilder.dp and
comment out the line that starts with: copy($sharedLibPath.$orig, $sharedLibFolder.':'.$dest).
- Open MacPerl and add the AmphetaDesk
lib/ directory to the @INC search.
- Open
AmphetaDesk.pl and uncomment the three lines that end with "for macintosh compile".
- Drop the
AmphetaDesk.pl script onto RuntimeBuilder.dp.
Once RuntimeBuilder.dp has finished, you'll have
a AmphetaDesk f within the current directory. This
will contain the AmphetaDesk.run application, and an
(possibly empty) directory called shared libs.
Currently, the shared libs directory needs to have
various MacPerl XS files copied into it (with their correct
directory structure). These are: InternetConfig, Memory,
Types, and /auto/XML/Parser/Expat/Expat.
Rename the AmphetaDesk f directory to your
archive name (see "Archive File Names" below) and copy over the
data/, docs/, gui/, and
templates/ directories. Make sure that there are no
CVS folders within those directories. Finally, you
should remove the following files/folders from the
data/ subdirectory: channels/,
internal/, lists/services-channels-complete.xml,
and lists/services-channels-failure.xml. These files
are either not needed or created automatically during normal
operation. You should also remove all docs/images/ss-*.jpg
files, as they are screenshots that are loaded from disobey.com -
they merely take up unnecessary space in the final archive.
At this point, it's very important that you open MacPerl, and
REMOVE the AmphetaDesk lib/ path that we added to
@INC. This addition was so Runtime Builder could
properly find our library files - leaving it enabled while we test
our application will give us a false sense of certainty.
Manually test the compiled AmphetaDesk.run (be
sure to rename it to just AmphetaDesk before
archiving) file for stability. When testing has completed, be sure
to remove the automagically generated data/channels/
and data/internal/ directories. If testing has completed
successfully, then Stuff and Binhex the folder and upload to
Sourceforge.
Macintosh (OS X) Build Notes
The OS X wrapper is a custom Cocoa application using Mac OS X
10.1.5 and the April 2002 Developer Tools. It was developed and
compiled by l.m.orchard with the Project- and Interface Builder
tools and the source code and documentation are available
from his site or by
requesting a copy from Morbus. If you learn anything from
his code, make sure you tell l.m.orchard you love him, because I
certainly do.
To create the Mac OS X binary:
- Doubleclick the
AmphetaDesk.pbproj file.
- Choose Build > Build. Wait patiently.
- Copy the
AmphetaDesk.app into the AmphetaDesk source directory.
At this point, manually test the compiled .app
file for stability. The .app runs the
AmphetaDesk.pl file, so make sure that interaction
between the two (browser opening, log display, etc.) happens as
intended. When you're satisifed that things are working fine,
we'll finalize our build by preping the directory for archiving
into our final disk image. You should remove the following files
and directories, which will insure a default installation of
AmphetaDesk:
- All
CVS/ directories.
- Anything in the
data/channels/ directory.
- All screenshots under
docs/images/.
- The
data/myChannels.opml file (and any backups).
- The
data/mySettings.xml file (and any backups).
At this point, you should be ready to create the archive,
named according to the format below.
Archive File Names
All completed archives should be named in the following conventions:
- amphetadesk-mac-v0.91.sit.hqx
- amphetadesk-osx-v0.93.dmg.gz
- amphetadesk-src-v0.90.tar.gz
- amphetadesk-win-v0.23.zip
Obviously, how the archives are compressed depends on the OS.
|
